////////||||||||||||||||||||||||||||||||\\\\\\\\
|||||||| Advent Vrsion 0.10 README File ||||||||
\\\\\\\\||||||||||||||||||||||||||||||||////////

////////|||||||||||||||\\\\\\\\\\\\\\\\\\\\\\\\\
|||||||| Instructions: |||||||||||||||||||||||||
\\\\\\\\|||||||||||||||/////////////////////////

1.  Download and install Notepad++ version 5.7 (Unicode) or later

2.  If you tell Notepad++ to install settings in %APPDATA% rather than its directory
    in "Program Files", keep in mind you will have to find the %APPDATA% directory

3.  Copy Advent.dll into the "plugins" subdirectory of the Notepad++ installation directory.
    e.g. If you installed Notepad++ to C:\Program Files\Notepad++, put it in the "plugins" subdirectory of that.
    
4.  Use xkas_advent.exe to rebuild your xkas version 0.06 source files (*.asm typically)
    This should produce a new file with the same name as the initial source file, but with a "dbg" extension.
    e.g. If you issue the command "xkas_advent.exe foo.asm foo.smc", then a file called foo.dbg will appear in the same directory
    
5.  Do not move this resultant *.dbg file unless you move it with the directory of your sources as a whole.
    Its location is used as a base for locating source files that may need to be opened, especially if you have
    assembly language files in subdirectories relative to your main source file.
    
6.  Keep bsnes_debugger.exe in the same folder as the QtCore4, QtGui, and QtNetwork DLLs.

7.  Start bsnes_debugger.exe, then execute the menu command "Tools > Debugger...".

8.  Execute the menu command "Misc > Start Debug Server"
    The output "Server started on localhost, port 0x5A22" should be printed in the console

9.  Go back to the main BSNES window and load the file that you assembled earlier (foo.smc).
    Note: bsnes doesn't display *.smc files by default, you will have to change the filter.
    This step can be avoided by renaming your target file to foo.sfc and
    changing the xkas command to "xkas_advent.exe foo.asm foo.sfc"
    
10. Open up Notepad++ and execute the Menu command "Plugins > Advent > Open Debug File..."

11. Open one or more of the source files that were used to assemble the rom.

12. Assign keyboard shortcuts if desired, they really speed up using debugging commands.
    Note: Notepad++ will not tell you if a keyboard shortcut is already in use, unfortunately
    
13. Set a breakpoint on a line of code you are interested in breaking at.
    A red diamond and red highlighting should show up on that line if the operation succeeded.
    Note: Only lines that contain at least one opcode are eligible to set a breakpoint on.
    In the event the line doesn't have any instructions "e.g. dw $0000, $0002", the Advent plugin
    will attempt to find a subsequent line that does have instructions in the same file and set a breakpoint there.

14. If the game reaches this point in the code, the bsnes_debugger.exe will snap and send a notification.
    Notepad++ should put a yellow double arrow + highlighting on the line it stops at.
    
15. Use stepping commands to better understand how your code is flowing and to debug problems.
    Have fun!
    
16. Potiential issues:
    - A rom for which not all the source is available, which is typical of a rom hack, will inevitably step out of the
      bounds of the code in the source files available. Set a breakpoint and issue a run command to resynchronize
      with the debugger from time to time. There is currently no way to tell if the game is running or stopped
      from Notepad++ at this time, though it's easy enough to switch to the BSNES windows to find out.
    
    - "Step Over" uses the current stack register value to determine when it is okay to stop executing.
      It is useful for stepping over JSR and JSL instructions, however it can be confusing to step over a
      PHA, PHY, PHX, PHP, etc... instruction. The debugger will halt when the stack level comes back up to what it was
      when the Step Over command was issued. e.g.
      
     1:  PHP ; <--- you issue a Step Over command from here
     2:
     3:  LDA $00
     4:  ASL A
     5:  ASL A
     6:  STA $00
     7: 
     8:  PLP ; <--- the current line marker will end up here, not at line 3 like one might expect.
     9:
     10: PHA : JSR SomeRoutine : PHA ; <--- issuing a Step Over command at the start of this line will end up at line 12, though
     11: 
     12: RTS ; <--- it will end up here because the stack has been balanced (assuming SomeRoutine also keeps the stack correct
      
      This can either be considered a bug or a feature, but given that assembly language is much more formless than,
      say, C++ code, I think it is a reasonable compromise.
      
    - Intentional changes to the stack register may interfere with stepping commands they swap out the existing stack for
      another location in memory. Since Step Over, Step End, and Step Out all depend on the stack, you could end up
      somewhere unexpected if this is the case. E.g. some games might use a different area of memory for the stack used for IRQ or NMI.

////////|||||||||||||\\\\\\\\\\\\\\\\\\\\\\\\\\\
|||||||| Known Bugs: |||||||||||||||||||||||||||
\\\\\\\\|||||||||||||///////////////////////////

(Version 0.10) The "Break" command works only sporadically, if at all
